DeepWiki

08.c - Deployment-Guide

Relevant source files

This document provides comprehensive instructions for deploying the godeep.wiki system to production, including Vercel hosting configuration, environment variable setup, automation script initialization, and operational monitoring. This guide assumes you have already configured your GitHub App and understand the required environment variables.

For detailed information about individual environment variables and their purposes, see Environment Variables. For GitHub App creation and configuration, see GitHub App Configuration.

Before beginning deployment, ensure you have:

RequirementPurposeVerification Command
Node.js 18+Runtime environmentnode --version
pnpmPackage managerpnpm --version
GitHub AppOAuth and repository accessApp created in GitHub settings
Stripe AccountPayment processingAccount created at stripe.com
Vercel AccountHosting platformAccount created at vercel.com
ntfy.sh TopicEvent notificationsTopic name reserved

Sources: README.md L43-L48

The following diagram illustrates the complete deployment architecture and how external services integrate with the Vercel-hosted application:

Deployment Components:

  • Vercel Infrastructure: Hosts the Next.js application with serverless API routes and edge functions
  • External Services: Third-party APIs that the application depends on for core functionality
  • Automation Infrastructure: Separate server running bash scripts that listen to ntfy.sh notifications
  • Environment Configuration: Split between Vercel-managed environment variables and local .env files

Sources: README.md L265-L290

scripts/README.md L1-L81

The fastest deployment method uses Vercel's GitHub integration:

Steps:

  1. Click the Deploy with Vercel button in README.md L271
  2. Connect your GitHub account to Vercel
  3. Configure environment variables (see section below)
  4. Vercel will automatically build and deploy

Sources: README.md L265-L272

For more control over the deployment process, use the Vercel CLI:

# Install Vercel CLI globallynpm install -g vercel# Authenticate with Vercelvercel login# Deploy to preview environmentvercel# Deploy to productionvercel --prod

Environment Variable Configuration via CLI:

# Add individual environment variablesvercel env add GITHUB_APP_SLUG productionvercel env add GITHUB_CLIENT_ID productionvercel env add GITHUB_CLIENT_SECRET productionvercel env add GITHUB_PRIVATE_KEY productionvercel env add NEXT_PUBLIC_ADMIN_PASSWORD productionvercel env add STRIPE_SECRET_KEY productionvercel env add STRIPE_WEBHOOK_SECRET productionvercel env add NTFY_TOPIC production# Pull environment variables to localvercel env pull .env.local

Sources: README.md L274-L290

For automated deployments on every commit:

  1. Connect Repository to Vercel: * Log into Vercel dashboard * Click "Add New Project" * Import your GitHub repository * Select godeep.wiki repository
  2. Configure Build Settings: * Framework Preset: Next.js * Build Command: pnpm build * Output Directory: .next * Install Command: pnpm install
  3. Configure Auto-Deployment: * Production Branch: main * Preview Deployments: Enabled for pull requests

Sources: README.md L265-L290

Environment variables must be configured in the Vercel dashboard before deployment. The following table maps environment variables to their Vercel configuration:

Variable NameCategoryRequiredExposed to ClientWhere to Get Value
GITHUB_APP_SLUGGitHubYesNoGitHub App settings URL slug
GITHUB_APP_IDGitHubYesNoGitHub App settings
GITHUB_CLIENT_IDGitHubYesNoGitHub App OAuth credentials
GITHUB_CLIENT_SECRETGitHubYesNoGitHub App OAuth credentials (regenerate)
GITHUB_PRIVATE_KEYGitHubYesNoGenerate in GitHub App settings
GITHUB_WEBHOOK_SECRETGitHubNoNoGenerate in GitHub App webhooks
NEXT_PUBLIC_APP_URLApplicationYesYesYour production domain
NEXT_PUBLIC_ADMIN_PASSWORDAdminYesYesChoose secure password
STRIPE_SECRET_KEYPaymentYesNoStripe dashboard API keys
STRIPE_PUBLISHABLE_KEYPaymentYesNoStripe dashboard API keys
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEYPaymentYesYesStripe dashboard API keys
STRIPE_WEBHOOK_SECRETPaymentYesNoStripe webhook endpoint
NTFY_TOPICAutomationYesNoYour ntfy.sh topic name
NEXT_PUBLIC_CF_BEACON_TOKENAnalyticsNoYesCloudflare Analytics

Vercel Configuration Diagram:

Configuration Steps:

  1. Navigate to project settings: https://vercel.com/<team>/<project>/settings/environment-variables
  2. Add each environment variable with appropriate environment scope
  3. Select environments: Production, Preview, Development as needed
  4. For GITHUB_PRIVATE_KEY, format as single line with \n for newlines
  5. Save and redeploy

Sources: .env.example L1-L15

README.md L72-L91

The automation scripts run separately from Vercel on a server or local machine that subscribes to ntfy.sh notifications. These scripts handle repository cloning after customers connect their GitHub accounts.

1. Dependency Installation:

# Install jq for JSON parsingbrew install jq  # macOS# ORsudo apt-get install jq  # Linux# Install GitHub CLIbrew install gh  # macOS# ORsudo apt-get install gh  # Linux# Authenticate GitHub CLIgh auth login

2. Environment Configuration:

Create a .env file in the project root with the admin password:

# .env file in project rootADMIN_PASSWORD=your_admin_password_here

Important: The ADMIN_PASSWORD in the local .env must match NEXT_PUBLIC_ADMIN_PASSWORD in Vercel environment variables.

Sources: scripts/README.md L9-L11

3. Script Execution:

# Navigate to project rootcd /path/to/godeep.wiki# Make script executablechmod +x scripts/ntfy-godeep-automation.sh# Run in foreground (for testing)./scripts/ntfy-godeep-automation.sh# Run in background (production)nohup ./scripts/ntfy-godeep-automation.sh > ~/ntfy-godeep.log 2>&1 &# Verify process is runningps aux | grep ntfy-godeep-automation# Monitor logs in real-timetail -f ~/ntfy-godeep.log

Sources: scripts/README.md L14-L21

The automation script executes the following sequence when triggered:

Sources: scripts/README.md L23-L51

TaskCommandDescription
Start foreground./scripts/ntfy-godeep-automation.shRun with console output
Start backgroundnohup ./scripts/ntfy-godeep-automation.sh > ~/ntfy-godeep.log 2>&1 &Daemonize script
Stop scriptpkill -f ntfy-godeep-automationTerminate running process
View logstail -f ~/ntfy-godeep.logMonitor real-time logs
Check statusps aux | grep ntfy-godeep-automationVerify script is running

Sources: scripts/README.md L54-L63

Post-Deployment VerificationLink copied!

After deploying to Vercel and starting the automation scripts, verify all system components are functioning correctly:

1. Landing Page Test:

curl -I https://your-domain.vercel.app# Expected: HTTP/2 200# Expected: content-type: text/html

2. GitHub OAuth Initiation Test:

curl -I https://your-domain.vercel.app/api/auth/github# Expected: HTTP/2 302# Expected: location: https://github.com/apps/your-app-slug/installations/new

3. Admin Panel Authentication Test:

curl -X POST https://your-domain.vercel.app/api/admin/generate-token \  -H "Content-Type: application/json" \  -d '{"password": "wrong_password", "installationId": "12345"}'# Expected: HTTP/2 401# Expected: {"error": "Invalid password"}

4. Stripe Webhook Test:

stripe trigger checkout.session.completed# Expected: Webhook received by /api/webhooks/stripe# Expected: ntfy notification sent

5. Automation Script Test:

# Send test notification to ntfy topiccurl -d "Test notification" https://ntfy.sh/your-topic# Check script logstail -n 20 ~/ntfy-godeep.log# Expected: Log entry showing notification received

Sources: README.md L314-L368

ComponentMonitoring MethodKey MetricsAlert Threshold
Vercel ApplicationVercel DashboardRequest count, error rate, latencyError rate > 5%
Stripe WebhooksStripe DashboardDelivery success, retriesFailed webhooks > 3
GitHub APIVercel LogsRate limit remaining, errorsRate limit < 100
ntfy.shScript logsMessage delivery, latencyMessage loss detected
Automation ScriptProcess monitoringProcess uptime, log errorsProcess down > 5 min
Disk SpaceServer monitoring~/godeep-clones/ sizeUsage > 80%

Vercel Logs:

# Install Vercel CLInpm install -g vercel# View real-time logsvercel logs --follow# Filter by functionvercel logs --function=/api/webhooks/stripe# Search logsvercel logs --query="installation_id"

Automation Script Logs:

# View recent logstail -n 100 ~/ntfy-godeep.log# Monitor in real-timetail -f ~/ntfy-godeep.log# Search for errorsgrep -i "error" ~/ntfy-godeep.log# Search for specific installationgrep "installation_id: 12345678" ~/ntfy-godeep.log

The following diagram shows where to look for correlation data when troubleshooting customer issues:

Sources: README diagrams (Diagram 5: Data Correlation and Tracking)

1. Vercel Analytics:

  • Already enabled by default for all deployments
  • View at: https://vercel.com/<team>/<project>/analytics

2. Stripe Dashboard Monitoring:

  • Configure webhook monitoring: https://dashboard.stripe.com/webhooks
  • Set up email alerts for failed webhooks

3. Automation Script Monitoring:

# Create monitoring cron jobcrontab -e# Add this line to check script every 5 minutes*/5 * * * * pgrep -f ntfy-godeep-automation || (echo "Script down!" | mail -s "Alert: Automation Script Down" admin@example.com)

4. Disk Space Monitoring:

# Check disk usage of clone directorydu -sh ~/godeep-clones/# Set up alert for disk spaceif [ $(du -s ~/godeep-clones/ | awk '{print $1}') -gt 10000000 ]; then    echo "Clone directory exceeds 10GB" | mail -s "Disk Space Alert" admin@example.comfi

Symptoms:

  • Deployment fails during build step
  • Error: "Type error: Cannot find module..."

Resolution:

  1. Verify all dependencies in package.json are installed
  2. Check TypeScript errors locally: pnpm build
  3. Ensure environment variables are set in Vercel
  4. Check build logs: vercel logs --scope=build

Sources: README.md L314-L368

Symptoms:

  • Runtime errors: "GITHUB_CLIENT_ID is undefined"
  • Authentication failures

Resolution:

  1. Verify variables are set in Vercel dashboard
  2. Ensure correct environment scope (Production/Preview/Development)
  3. Redeploy after adding variables
  4. Check variable names match exactly (case-sensitive)
# Verify variables are loadedvercel env ls# Pull variables locally to verifyvercel env pull .env.localcat .env.local

Sources: .env.example L1-L15

Symptoms:

  • Script process is running but not cloning repositories
  • No log entries in ~/ntfy-godeep.log

Resolution:

  1. Verify ntfy topic name matches: NTFY_TOPIC in Vercel and script
  2. Test ntfy subscription manually:
curl -s https://ntfy.sh/your-topic/json
  1. Check network connectivity to ntfy.sh
  2. Verify .env file exists in project root
  3. Check script has read permissions for .env

Sources: scripts/README.md L65-L81

Symptoms:

  • Error: "Invalid client credentials"
  • OAuth flow redirects to error page

Resolution:

  1. Verify GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET match GitHub App settings
  2. Check callback URL is correct: https://your-domain.vercel.app/api/auth/github/callback
  3. Ensure GitHub App is installed in the correct organization/account
  4. Regenerate client secret and update in Vercel

Sources: README.md L320-L353

Symptoms:

  • Error: "No signatures found matching the expected signature"
  • Webhooks marked as failed in Stripe dashboard

Resolution:

  1. Verify STRIPE_WEBHOOK_SECRET matches webhook endpoint in Stripe
  2. Check webhook endpoint URL: https://your-domain.vercel.app/api/webhooks/stripe
  3. Ensure webhook secret is for the correct endpoint (test vs. production)
  4. Test webhook manually from Stripe dashboard

Sources: README.md L314-L368

Symptoms:

  • Script errors: "No space left on device"
  • Clone operations fail

Resolution:

# Check disk usagedf -h ~# List large clone directoriesdu -sh ~/godeep-clones/* | sort -hr | head -10# Clean up old clones (if needed)rm -rf ~/godeep-clones/old-customer-repo/# The script should auto-cleanup after pushing to GitHub# If not, check script logs for push failures

Sources: scripts/README.md L23-L51

Use this checklist before marking deployment as production-ready:

  • All environment variables configured in Vercel
  • GitHub App created and configured with correct permissions
  • Stripe account configured with webhook endpoint
  • ntfy.sh topic reserved and configured
  • .env file created on automation server with ADMIN_PASSWORD
  • Dependencies installed on automation server (jq, gh, git)
  • GitHub CLI authenticated on automation server
  • Code pushed to main branch
  • Vercel deployment completed successfully
  • Build logs checked for errors
  • Environment variables verified in Vercel dashboard
  • Production domain configured

Post-DeploymentLink copied!

  • Landing page loads correctly
  • Payment flow tested (use Stripe test mode)
  • GitHub OAuth flow tested
  • Admin panel accessible with correct password
  • Automation script started on server
  • Test notification sent to ntfy.sh topic
  • Test repository clone successful
  • Logs monitoring configured
  • Alert system configured
  • All secrets rotated from test/development values
  • GITHUB_PRIVATE_KEY formatted correctly (single line with \n)
  • Admin password is strong and unique
  • Webhook secrets are unique and secure
  • GitHub App permissions are minimal (read-only)
  • Automation server has restricted access

Sources: README.md L393-L406

While the current architecture is designed for low-volume manual operation, consider these optimizations if scaling is needed:

BottleneckCurrent LimitationScaling Solution
Manual CorrelationRequires log inspection to link payments to installationsImplement database to store session_id → installation_id mappings
Single Automation ServerOne server running bash scriptDeploy multiple script instances with load balancing
Disk SpaceClones stored temporarily on single serverUse ephemeral containers for cloning (Docker/Kubernetes)
Manual DocumentationOwner generates documentation manuallyImplement automated documentation generation pipeline
ntfy.sh DependencySingle point of failure for notificationsAdd message queue redundancy (RabbitMQ/Redis)

Note: The system is intentionally simple for the current low-volume use case. These scaling improvements should only be implemented if volume increases significantly.

Sources: README diagrams (Analysis sections)

Refresh this wiki

Last indexed: 23 November 2025 (922b35)

On this page

Ask Devin about godeep.wiki-jb

Syntax error in text

mermaid version 11.4.1

08.c - Deployment-Guide | DeepWiki | godeep.wiki